lib/mailtrap/account.rb (1)

6-8: Consider using @!attribute [r] instead of @attr_reader for Struct fields.

@attr_reader is not a standard YARD tag; @!attribute [r] is the idiomatic YARD macro for documenting read-only Struct/class attributes and will be correctly picked up by YARD's parser.

♻️ Proposed refactor

-  # `@attr_reader` id [Integer] The account ID
-  # `@attr_reader` name [String] The account name
-  # `@attr_reader` access_levels [Array] The account access levels
+  # @!attribute [r] id
+  #   `@return` [Integer] The account ID
+  # @!attribute [r] name
+  #   `@return` [String] The account name
+  # @!attribute [r] access_levels
+  #   `@return` [Array] The account access levels

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/mailtrap/account.rb` around lines 6 - 8, Replace the nonstandard YARD
tags `@attr_reader` with the idiomatic `@!attribute [r]` doc macro for the
Struct fields (id, name, access_levels) in lib/mailtrap/account.rb so YARD
properly recognizes them; update each docline to use `@!attribute [r] id`,
`@!attribute [r] name`, and `@!attribute [r] access_levels` (preserving the
existing type and description) and remove the old `@attr_reader` entries.

spec/mailtrap/accounts_api_spec.rb (2)

12-15: Add field-level assertions to verify Account struct mapping.

The test confirms the type and count of returned objects but never verifies that the individual fields (id, name, access_levels) are actually populated from the API response. A bug in field mapping (e.g., wrong key name) would pass this test. Since the VCR cassette produces deterministic data, this is straightforward to add.

♻️ Proposed addition

 it 'maps response data to Account objects' do
   expect(list).to all(be_a(Mailtrap::Account))
   expect(list.size).to eq(1)
+
+  account = list.first
+  expect(account.id).to be_a(Integer)
+  expect(account.name).to be_a(String)
+  expect(account.access_levels).to be_an(Array)
 end

Alternatively, pin the exact values from the VCR cassette fixture to tighten the contract:

+  expect(account.id).to eq(123456)
+  expect(account.name).to eq('My Account')
+  expect(account.access_levels).to eq([1000])

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@spec/mailtrap/accounts_api_spec.rb` around lines 12 - 15, The test only
asserts types and count for 'list' but not field mapping; update the spec in
spec/mailtrap/accounts_api_spec.rb to assert that each Mailtrap::Account in
'list' has correctly populated fields by checking account.id, account.name and
account.access_levels against the expected values from the VCR cassette (or at
minimum that they are not nil/empty); reference the Mailtrap::Account objects
returned in 'list' and add expectations for id, name and access_levels to ensure
the API response keys are mapped properly.

---

22-25: Remove redundant assertion on line 24.

The error.messages array is joined into error.message (messages.join(', ')), so checking error.message.include?(...) on line 23 and error.messages.any? { |msg| msg.include?(...) } on line 24 tests the same data path twice. Keep line 23 and remove line 24.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@spec/mailtrap/accounts_api_spec.rb` around lines 22 - 25, Remove the
redundant assertion that checks error.messages (the expectation using
error.messages.any? { |msg| msg.include?('Incorrect API token') }) in the spec;
keep the existing check that inspects error.message.include?('Incorrect API
token') and delete the second expectation so the spec only asserts the message
once (refer to the expectations around Mailtrap::AuthorizationError and the
lines that call error.message.include? and error.messages.any?).

examples/accounts_api.rb (2)

14-14: accounts.list return value is silently discarded when run as a script.

In an IRB/REPL session the result is printed automatically, but when the file is executed with ruby examples/accounts_api.rb the return value is thrown away and no output appears. Assign the result or use p/pp so the example is self-contained and demonstrable as a runnable script.

♻️ Proposed fix

-accounts.list
+result = accounts.list
+pp result
 # => [#<struct Mailtrap::Account id=123456, name="My Account", access_levels=[1000]>]

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@examples/accounts_api.rb` at line 14, The script calls accounts.list but
discards its return value, so running the file prints nothing; update the
example to surface the result by assigning the return to a variable (e.g.,
result = accounts.list) and then print it (e.g., p result or puts
result.inspect), or directly wrap the call with p/pp (p accounts.list) so the
script is demonstrable when executed; modify the line containing accounts.list
accordingly.

---

3-14: Consider restructuring the example so the env-var pattern is the active code.

The current flow is logically inverted: hardcoded credentials are used to build the client/accounts objects (lines 3–5), and only afterward does the comment tell the reader to use environment variables (lines 7–9), with the preferred no-arg form commented out (line 11). A reader scanning top-to-bottom will use the hardcoded values without realising the env-var pattern even exists.

Additionally, account_id = 3229 looks like a real account ID rather than a recognisable placeholder. For consistency with 'your-api-key' it should be something like 100_000 or 'your-account-id'.

♻️ Proposed restructure

 require 'mailtrap'

+# Option 1: Provide credentials explicitly
+client     = Mailtrap::Client.new(api_key: 'your-api-key')
+account_id = 100_000
+accounts   = Mailtrap::AccountsAPI.new(account_id, client)
+
+# Option 2: Set credentials via environment variables and use defaults
 # export MAILTRAP_API_KEY='your-api-key'
 # export MAILTRAP_ACCOUNT_ID=your-account-id
-
-client = Mailtrap::Client.new(api_key: 'your-api-key')
-account_id = 3229
-accounts = Mailtrap::AccountsAPI.new(account_id, client)
-
-# Set your API credentials as environment variables
-# export MAILTRAP_API_KEY='your-api-key'
-# export MAILTRAP_ACCOUNT_ID=your-account-id
-
-# accounts = Mailtrap::AccountsAPI.new
+# accounts = Mailtrap::AccountsAPI.new

 # Get all accounts
-accounts.list
+result = accounts.list
 # => [#<struct Mailtrap::Account id=123456, name="My Account", access_levels=[1000]>]

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@examples/accounts_api.rb` around lines 3 - 14, The example currently
constructs Mailtrap::Client.new and Mailtrap::AccountsAPI.new using hardcoded
values before showing the env-var pattern; reorder the snippet so the active
code reads credentials from ENV (use ENV['MAILTRAP_API_KEY'] and
ENV['MAILTRAP_ACCOUNT_ID'] to build Mailtrap::Client.new and
Mailtrap::AccountsAPI.new) and use a clearly placeholder account_id like 100_000
or 'your-account-id'; move the hardcoded example into a commented block below as
an alternative and keep the call to accounts.list as the final action so readers
run the env-var flow by default (refer to Mailtrap::Client.new,
Mailtrap::AccountsAPI.new, account_id, and accounts.list when making the
change).

lib/mailtrap/account.rb (2)

6-8: @attr_reader is deprecated in YARD since 0.8.0; prefer @!attribute [r].

@attr tags have been deprecated since YARD 0.8.0 in favour of the @!attribute directive. YARD's own tag docs recommend using "the more powerful @!attribute directive instead," noting that @attr_reader is "only applicable on class docstrings" and "declares a readonly attribute on a Struct or class." The Account = Struct.new(...) constant-assignment form is not a class docstring, so YARD's StructHandler may not pick up these tags correctly regardless.

📝 Proposed fix

-  # `@attr_reader` id [Integer] The account ID
-  # `@attr_reader` name [String] The account name
-  # `@attr_reader` access_levels [Array] The account access levels
+  # @!attribute [r] id
+  #   `@return` [Integer] The account ID
+  # @!attribute [r] name
+  #   `@return` [String] The account name
+  # @!attribute [r] access_levels
+  #   `@return` [Array] The account access levels

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/mailtrap/account.rb` around lines 6 - 8, Replace deprecated YARD
`@attr_reader` tags for the Account Struct with @!attribute directives: add
@!attribute [r] id, @!attribute [r] name and @!attribute [r] access_levels
(including their types and short descriptions) near the Account =
Struct.new(...) declaration so YARD's StructHandler will pick them up correctly;
ensure the attributes are documented as readonly and that the text mirrors the
existing comments (Integer for id, String for name, Array for access_levels).

---

6-8: Use @!attribute [r] instead of @attr_reader for YARD documentation.

The @attr_reader tag is not recognized by the YARD parser and will not render in API documentation. The correct YARD directive for documenting readable attributes is @!attribute [r].

📝 Proposed fix

-  # `@attr_reader` id [Integer] The account ID
-  # `@attr_reader` name [String] The account name
-  # `@attr_reader` access_levels [Array] The account access levels
+  # @!attribute [r] id
+  #   `@return` [Integer] The account ID
+  # @!attribute [r] name
+  #   `@return` [String] The account name
+  # @!attribute [r] access_levels
+  #   `@return` [Array] The account access levels

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/mailtrap/account.rb` around lines 6 - 8, Replace the non-standard YARD
tags by changing each "@attr_reader" doc line for the Account attributes to the
supported YARD directive "@!attribute [r]" and keep the type and
description—i.e., update the doc comments referencing id, name, and
access_levels in lib/mailtrap/account.rb so they become "@!attribute [r] id
[Integer] The account ID", "@!attribute [r] name [String] The account name", and
"@!attribute [r] access_levels [Array] The account access levels" (preserve
wording/types for id, name, access_levels) so YARD will render them as readable
attributes.